home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 27 / CU Amiga Magazine's Super CD-ROM 27 (1998)(EMAP Images)(GB)[!][issue 1998-10].iso / CUCD / Programming / MCCImageButton / Developer / Autodocs / MCC_ImageButton.doc
Encoding:
Text File  |  1998-08-17  |  10.7 KB  |  307 lines
  1. TABLE OF CONTENTS
  2.  
  3. ImageButton.mcc/--announcement--
  4. ImageButton.mcc/ImageButton.mcc
  5. ImageButton.mcc/MUIA_ImageButton_Image
  6. ImageButton.mcc/MUIA_ImageButton_Label
  7. ImageButton.mcc/MUIA_ImageButton_LabelPos
  8. ImageButton.mcc/--announcement--             ImageButton.mcc/--announcement--
  9.  
  10.    TITLE
  11.        ImageButton.mcc
  12.  
  13.    VERSION
  14.        11.3
  15.  
  16.    RELEASE DATE
  17.        17.08.1998
  18.  
  19.    DESCRIPTION
  20.        Instead of creating simple and rather boring text buttons, Image-
  21.        Button.mcc allows the programmer to add every type of static graphics
  22.        to the buttons. This way, your graphical user interface will be more
  23.        user-friendly and the users will like to use it more often.
  24.  
  25.        You can set the image, the label and the label position of a button
  26.        at any time. It is also possible to show/hide the image and/or the
  27.        label at any time.
  28.  
  29.    SPECIAL REQUIREMENTS
  30.        MUI 3.0+
  31.  
  32.    AVAILABILITY
  33.        http://www.IQ-Computing.de
  34.        ftp://ftp.iq-computing.de/pub/MCC_ImageButton.lha
  35.        ftp://ftp.wustl.edu/pub/aminet/dev/mui/MCC_ImgButton.lha
  36.  
  37.    PRICE
  38.        Freeware
  39.        Please read the additional License.txt document for further details.
  40.  
  41.    NEW FEATURES
  42.        - major speed-up improvement when a button needs to be visually
  43.          updated (eg. when changing the image, label or label position)
  44.  
  45.    AUTHOR
  46.        Maik "bZ!" Schreiber <bZ@iq-computing.de>
  47.        www.IQ-Computing.de
  48.  
  49.    DISTRIBUTION
  50.        Please read the additional License.txt document for further details.
  51. ImageButton.mcc/ImageButton.mcc               ImageButton.mcc/ImageButton.mcc
  52.  
  53. Instead of creating simple and rather boring text buttons, ImageButton.mcc
  54. allows the programmer to add every type of static graphics to the buttons.
  55. This way, your graphical user interface will be more user-friendly and the
  56. users will like to use it more often.
  57.  
  58. You can set the image, the label and the label position of a button at any
  59. time. It is also possible to show/hide the image and/or the label at any
  60. time.
  61.  
  62. See the supplied demonstration program for more details.
  63.  
  64.  
  65. Some additional notes:
  66.  
  67.  
  68. ImageButtons can contain the following types of static graphics, only one at
  69. a time for each button:
  70.  
  71. - graphics loaded via DataTypes
  72. - ILBM BODY data in memory (provides all features of Bodychunk.mui)
  73. - Image specifications (provides all features of Image.mui)
  74.  
  75. Please note that when an image cannot be created (DataTypes system not
  76. available, not enough free store...), the image will simply be hidden. No
  77. errors will occur.
  78.  
  79.  
  80. ImageButton.mcc usually creates a full-featured button, that means with a
  81. button frame, button background and button font. If you want to change these
  82. attributes, just set them as usual (use MUIA_Frame, MUIA_Background and
  83. MUIA_Font). Remember that it's not wise the change them, though. You should
  84. have a good reason for doing that.
  85.  
  86. Whenever an image and a label are both displayed, ImageButton.mcc will
  87. insert a space between them, which is at least 3 pixels high (in vertical
  88. buttons) or 10 pixels wide (in horizontal buttons).
  89.  
  90.  
  91. ImageButtons do not have a fixed size. If you eg. want to create a fixed-
  92. height horizontal button with an image, you should use MUIA_VertWeight with 0
  93. to limit its height.
  94.  
  95. If you eg. want a horizontal group with three ImageButtons with the same
  96. height each, but as small as possible, you should use the following:
  97.  
  98.   Child, HGroup,
  99.     Child, button1 = ImageButtonObject,
  100.       /* ... */
  101.     End,
  102.     Child, button2 = ImageButtonObject,
  103.       /* ... */
  104.     End,
  105.     Child, button3 = ImageButtonObject,
  106.       /* ... */
  107.     End,
  108.     MUIA_VertWeight, 0,
  109.   End,
  110. ImageButton.mcc/MUIA_ImageButton_Image ImageButton.mcc/MUIA_ImageButton_Image
  111.  
  112.    NAME
  113.        MUIA_ImageButton_Image -- [ISG], struct MUIS_ImageButton_Image *
  114.  
  115.    FUNCTION
  116.        Set or get the image of a button. NULL will hide the image. If there
  117.        already is an image being displayed, it will be removed and replaced
  118.        by the new one.
  119.  
  120.        You have to pass a pointer to a MUIS_ImageButton_Image structure,
  121.        which has the following elements:
  122.  
  123.        ibi_ImageType -- ULONG (always)
  124.            Specifies the image type of the image:
  125.  
  126.                MUIV_ImageButton_ImageType_File:
  127.                    An external file will be loaded into memory via Data-
  128.                    Types.
  129.  
  130.                MUIV_ImageButton_ImageType_Body:
  131.                    A BODY chunk of an ILBM file in memory will be displayed.
  132.                    See Bodychunk.mui/MUIA_Bodychunk_Body for details.
  133.  
  134.                MUIV_ImageButton_ImageType_Image:
  135.                    A MUI Image specification will be displayed.
  136.                    See Image.mui for details.
  137.  
  138.  
  139.        The following elements do not need to be specified always, but only
  140.        if their corresponding image type is used. The abbreviations in
  141.        brackets have the following meanings:
  142.  
  143.            file  -- ibi_ImageType is set to MUIV_ImageButton_ImageType_File
  144.            BODY  -- ibi_ImageType is set to MUIV_ImageButton_ImageType_Body
  145.            Image -- ibi_ImageType is set to MUIV_ImageButton_ImageType_Image
  146.  
  147.  
  148.        ibi_Precision -- LONG (file & BODY)
  149.            Specifies the precision for remapping the image.
  150.            See Bitmap.mui/MUIA_Bitmap_Precision and graphics.library/
  151.            ObtainBestPenA() for details.
  152.  
  153.        ibi_UseFriend -- BOOL (file & BODY)
  154.            Specifies if you want to use a friend bitmap.
  155.            See Bitmap.mui/MUIA_Bitmap_UseFriend and picture.datatype/
  156.            picture.datatype for details.
  157.  
  158.        ibi_Filename -- STRPTR (file)
  159.            Specifies the external file to be loaded into memory via
  160.            DataTypes. If the DataTypes system is not available (eg. pre-V39)
  161.            or the file cannot be loaded, the image will simply be hidden.
  162.  
  163.        ibi_Body -- UBYTE * (BODY)
  164.            Pointer to the BODY chunk of ILBM data in memory to be displayed.
  165.            If the image cannot be created, it will simply be hidden.
  166.            See Bodychunk.mui/MUIA_Bodychunk_Body for details.
  167.  
  168.        ibi_Width -- ULONG (BODY)
  169.            The width of the image.
  170.            See Bitmap.mui/MUIA_Bitmap_Width for details.
  171.  
  172.        ibi_Height -- ULONG (BODY)
  173.            The height of the image.
  174.            See Bitmap.mui/MUIA_Bitmap_Height for details.
  175.  
  176.        ibi_Depth -- ULONG (BODY)
  177.            The depth of the image.
  178.            See Bodychunk.mui/MUIA_Bodychunk_Depth for details.
  179.  
  180.        ibi_Masking -- UBYTE (BODY)
  181.            Specifies the masking planes.
  182.            See Bodychunk.mui/MUIA_Bodychunk_Masking for details.
  183.  
  184.        ibi_Compression -- UBYTE (BODY)
  185.            Specifies if the BODY chunk is compressed.
  186.            See Bodychunk.mui/MUIA_Bodychunk_Compression for details.
  187.  
  188.        ibi_Transparent -- LONG (BODY)
  189.            Specifies which color should be transparent (if you don't want
  190.            transparency, give MUIV_ImageButton_Transparent_None).
  191.            See Bitmap.mui/MUIA_Bitmap_Transparent for details.
  192.  
  193.        ibi_SourceColors -- ULONG * (BODY)
  194.            Pointer to color array containing the colors of the image.
  195.            See Bitmap.mui/MUIA_Bitmap_SourceColors for details.
  196.  
  197.        ibi_MappingTable -- UBYTE * (BODY)
  198.            Pointer to an array of UBYTEs, used for remapping the image.
  199.            See Bitmap.mui/MUIA_Bitmap_MappingTable for details.
  200.  
  201.        ibi_FontMatchWidth -- BOOL (Image)
  202.            If TRUE, the width of the given image will be scaled to match the
  203.            current font.
  204.            See Image.mui/MUIA_Image_FontMatchWidth for details.
  205.  
  206.        ibi_FontMatchHeight -- BOOL (Image)
  207.            If TRUE, the height of the given image will be scaled to match
  208.            the current font.
  209.            See Image.mui/MUIA_Image_FontMatchHeight for details.
  210.  
  211.        ibi_FreeHoriz -- BOOL (Image)
  212.            Tell the image if it's allowed to get scaled horizontally.
  213.            See Image.mui/MUIA_Image_FreeHoriz for details.
  214.  
  215.        ibi_FreeVert -- BOOL (Image)
  216.            Tell the image if it's allowed to get scaled vertically.
  217.            See Image.mui/MUIA_Image_FreeVert for details.
  218.  
  219.        ibi_OldImage -- struct Image * (Image)
  220.            Allows you to use any conventional image structure. If you don't
  221.            want use Image structures, supply NULL. If the image cannot be
  222.            created, it will simply be hidden.
  223.            See Image.mui/MUIA_Image_OldImage for details.
  224.  
  225.        ibi_Spec -- STRPTR (Image)
  226.            Specify a MUI Image specification. If you don't want to use MUI
  227.            image specifications, supply NULL. If the image cannot be
  228.            created, it will simply be hidden.
  229.            See Image.mui/MUIA_Image_Spec for details.
  230.  
  231.        ibi_State -- LONG (Image)
  232.          Specify the state of the image.
  233.          See Image.mui/MUIA_Image_State for details.
  234.  
  235.    EXAMPLE
  236.        Please refer to the ImageButton.mcc example program.
  237.  
  238.    NOTES
  239.        The input will be buffered, you may destroy your private structure
  240.        after setting this attribute.
  241.  
  242.        You may not modify the returned structure.
  243.  
  244.    SEE ALSO
  245.        Bodychunk.mui, Bitmap.mui, Image.mui
  246. ImageButton.mcc/MUIA_ImageButton_Label ImageButton.mcc/MUIA_ImageButton_Label
  247.  
  248.    NAME
  249.        MUIA_ImageButton_Label -- [ISG], STRPTR
  250.  
  251.    FUNCTION
  252.        Set or get the label of a button. NULL will hide the label. If there
  253.        is already a label being displayed, it will be removed and replaced
  254.        by the new one.
  255.  
  256.        The label may contain an underscore character ("_"), which is used to
  257.        indicate to control key.
  258.  
  259.    EXAMPLE
  260.        obj = ImageButtonObject,
  261.          MUIA_ImageButton_Label, "_Quit",
  262.        End;
  263.  
  264.    NOTES
  265.        When hiding the label, the control key gets disabled. If you want a
  266.        control key though, you have to set MUIA_ControlChar yourself after
  267.        hiding the label.
  268.  
  269.        Setting an empty string ("") will *not* hide the label but replace it
  270.        with an empty one.
  271.  
  272.        The label is currently limited to a length of 80 characters.
  273.  
  274.        The input will be buffered, you may destroy your private string after
  275.        setting this attribute.
  276.  
  277.        You may not modify the returned string.
  278.  
  279.    SEE ALSO
  280.        Area.mui/MUIA_ControlChar
  281. ImageButton.mcc/MUIA_ImageButton_LabelPosButton.mcc/MUIA_ImageButton_LabelPos
  282.  
  283.    NAME
  284.        MUIA_ImageButton_LabelPos -- [ISG], ULONG
  285.  
  286.    FUNCTION
  287.        Forces the label of an ImageButton to be at the specified position.
  288.        If the position is already set, nothing will happen.
  289.  
  290.        Default: MUIV_ImageButton_LabelPos_Bottom
  291.  
  292.    SPECIAL INPUTS
  293.        MUIV_ImageButton_LabelPos_Bottom
  294.            The label will be below the image.
  295.  
  296.        MUIV_ImageButton_LabelPos_Right
  297.            The label will be right from the image.
  298.  
  299.        MUIV_ImageButton_LabelPos_Left
  300.            The label will be left from the image.
  301.  
  302.        MUIV_ImageButton_LabelPos_Top
  303.            The label will be above the image.
  304.  
  305.    NOTES
  306.        You may only set one of the special inputs, no other input will work.
  307.